home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / info / gnus.info-10.z / gnus.info-10
Encoding:
GNU Info File  |  1998-05-21  |  46.3 KB  |  1,244 lines
  1. This is Info file ../info/gnus.info, produced by Makeinfo version 1.68
  2. from the input file gnus.texi.
  3.  
  4.    This file documents Gnus, the GNU Emacs newsreader.
  5.  
  6.    Copyright (C) 1995,96 Free Software Foundation, Inc.
  7.  
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.  
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided also
  14. that the entire resulting derived work is distributed under the terms
  15. of a permission notice identical to this one.
  16.  
  17.    Permission is granted to copy and distribute translations of this
  18. manual into another language, under the above conditions for modified
  19. versions.
  20.  
  21. 
  22. File: gnus.info,  Node: Red Gnus,  Prev: September Gnus,  Up: New Features
  23.  
  24. Red Gnus
  25. ........
  26.  
  27.    New features in Gnus 5.4/5.5:
  28.  
  29.    * `nntp.el' has been totally rewritten in an asynchronous fashion.
  30.  
  31.    * Article prefetching functionality has been moved up into Gnus
  32.      (*note Asynchronous Fetching::.).
  33.  
  34.    * Scoring can now be performed with logical operators like `and',
  35.      `or', `not', and parent redirection (*note Advanced Scoring::.).
  36.  
  37.    * Article washing status can be displayed in the article mode line
  38.      (*note Misc Article::.).
  39.  
  40.    * `gnus.el' has been split into many smaller files.
  41.  
  42.    * Suppression of duplicate articles based on Message-ID can be done
  43.      (*note Duplicate Suppression::.).
  44.  
  45.           (setq gnus-suppress-duplicates t)
  46.  
  47.    * New variables for specifying what score and adapt files are to be
  48.      considered home score and adapt files (*note Home Score File::.)
  49.      have been added.
  50.  
  51.    * `nndoc' was rewritten to be easily extendable (*note Document
  52.      Server Internals::.).
  53.  
  54.    * Groups can inherit group parameters from parent topics (*note
  55.      Topic Parameters::.).
  56.  
  57.    * Article editing has been revamped and is now actually usable.
  58.  
  59.    * Signatures can be recognized in more intelligent fashions (*note
  60.      Article Signature::.).
  61.  
  62.    * Summary pick mode has been made to look more `nn'-like.  Line
  63.      numbers are displayed and the `.' command can be used to pick
  64.      articles (`Pick and Read').
  65.  
  66.    * Commands for moving the `.newsrc.eld' from one server to another
  67.      have been added (*note Changing Servers::.).
  68.  
  69.    * There's a way now to specify that "uninteresting" fields be
  70.      suppressed when generating lines in buffers (*note Advanced
  71.      Formatting::.).
  72.  
  73.    * Several commands in the group buffer can be undone with `M-C-_'
  74.      (*note Undo::.).
  75.  
  76.    * Scoring can be done on words using the new score type `w' (*note
  77.      Score File Format::.).
  78.  
  79.    * Adaptive scoring can be done on a Subject word-by-word basis
  80.      (*note Adaptive Scoring::.).
  81.  
  82.           (setq gnus-use-adaptive-scoring '(word))
  83.  
  84.    * Scores can be decayed (*note Score Decays::.).
  85.  
  86.           (setq gnus-decay-scores t)
  87.  
  88.    * Scoring can be performed using a regexp on the Date header.  The
  89.      Date is normalized to compact ISO 8601 format first (*note Score
  90.      File Format::.).
  91.  
  92.    * A new command has been added to remove all data on articles from
  93.      the native server (*note Changing Servers::.).
  94.  
  95.    * A new command for reading collections of documents (`nndoc' with
  96.      `nnvirtual' on top) has been added--`M-C-d' (*note Really Various
  97.      Summary Commands::.).
  98.  
  99.    * Process mark sets can be pushed and popped (*note Setting Process
  100.      Marks::.).
  101.  
  102.    * A new mail-to-news backend makes it possible to post even when the
  103.      NNTP server doesn't allow posting (*note Mail-To-News Gateways::.).
  104.  
  105.    * A new backend for reading searches from Web search engines
  106.      ("DejaNews", "Alta Vista", "InReference") has been added (*note
  107.      Web Searches::.).
  108.  
  109.    * Groups inside topics can now be sorted using the standard sorting
  110.      functions, and each topic can be sorted independently (*note Topic
  111.      Sorting::.).
  112.  
  113.    * Subsets of the groups can be sorted independently (`Sorting
  114.      Groups').
  115.  
  116.    * Cached articles can be pulled into the groups (*note Summary
  117.      Generation Commands::.).
  118.  
  119.    * Score files are now applied in a more reliable order (*note Score
  120.      Variables::.).
  121.  
  122.    * Reports on where mail messages end up can be generated (*note
  123.      Splitting Mail::.).
  124.  
  125.    * More hooks and functions have been added to remove junk from
  126.      incoming mail before saving the mail (*note Washing Mail::.).
  127.  
  128.    * Emphasized text can be properly fontisized:
  129.  
  130.           (add-hook 'gnus-article-display-hook 'gnus-article-emphasize)
  131.  
  132. 
  133. File: gnus.info,  Node: Newest Features,  Prev: New Features,  Up: History
  134.  
  135. Newest Features
  136. ---------------
  137.  
  138.    Also known as the "todo list".  Sure to be implemented before the
  139. next millennium.
  140.  
  141.    Be afraid.  Be very afraid.
  142.  
  143.    * Native MIME support is something that should be done.
  144.  
  145.    * Really do unbinhexing.
  146.  
  147.    And much, much, much more.  There is more to come than has already
  148. been implemented.  (But that's always true, isn't it?)
  149.  
  150.    `<URL:http://www.ifi.uio.no/~larsi/rgnus/todo>' is where the actual
  151. up-to-the-second todo list is located, so if you're really curious, you
  152. could point your Web browser over that-a-way.
  153.  
  154. 
  155. File: gnus.info,  Node: Terminology,  Next: Customization,  Prev: History,  Up: Appendices
  156.  
  157. Terminology
  158. ===========
  159.  
  160. "news"
  161.      This is what you are supposed to use this thing for--reading news.
  162.      News is generally fetched from a nearby NNTP server, and is
  163.      generally publicly available to everybody.  If you post news, the
  164.      entire world is likely to read just what you have written, and
  165.      they'll all snigger mischievously.  Behind your back.
  166.  
  167. "mail"
  168.      Everything that's delivered to you personally is mail.  Some
  169.      news/mail readers (like Gnus) blur the distinction between mail
  170.      and news, but there is a difference.  Mail is private.  News is
  171.      public.  Mailing is not posting, and replying is not following up.
  172.  
  173. "reply"
  174.      Send a mail to the person who has written what you are reading.
  175.  
  176. "follow up"
  177.      Post an article to the current newsgroup responding to the article
  178.      you are reading.
  179.  
  180. "backend"
  181.      Gnus gets fed articles from a number of backends, both news and
  182.      mail backends.  Gnus does not handle the underlying media, so to
  183.      speak--this is all done by the backends.
  184.  
  185. "native"
  186.      Gnus will always use one method (and backend) as the "native", or
  187.      default, way of getting news.
  188.  
  189. "foreign"
  190.      You can also have any number of foreign groups active at the same
  191.      time.  These are groups that use non-native non-secondary backends
  192.      for getting news.
  193.  
  194. "secondary"
  195.      Secondary backends are somewhere half-way between being native and
  196.      being foreign, but they mostly act like they are native.
  197.  
  198. "article"
  199.      A message that has been posted as news.
  200.  
  201. "mail message"
  202.      A message that has been mailed.
  203.  
  204. "message"
  205.      A mail message or news article
  206.  
  207. "head"
  208.      The top part of a message, where administrative information (etc.)
  209.      is put.
  210.  
  211. "body"
  212.      The rest of an article.  Everything not in the head is in the body.
  213.  
  214. "header"
  215.      A line from the head of an article.
  216.  
  217. "headers"
  218.      A collection of such lines, or a collection of heads.  Or even a
  219.      collection of NOV lines.
  220.  
  221. "NOV"
  222.      When Gnus enters a group, it asks the backend for the headers of
  223.      all unread articles in the group.  Most servers support the News
  224.      OverView format, which is more compact and much faster to read and
  225.      parse than the normal HEAD format.
  226.  
  227. "level"
  228.      Each group is subscribed at some "level" or other (1-9).  The ones
  229.      that have a lower level are "more" subscribed than the groups with
  230.      a higher level.  In fact, groups on levels 1-5 are considered
  231.      "subscribed"; 6-7 are "unsubscribed"; 8 are "zombies"; and 9 are
  232.      "killed".  Commands for listing groups and scanning for new
  233.      articles will all use the numeric prefix as "working level".
  234.  
  235. "killed groups"
  236.      No information on killed groups is stored or updated, which makes
  237.      killed groups much easier to handle than subscribed groups.
  238.  
  239. "zombie groups"
  240.      Just like killed groups, only slightly less dead.
  241.  
  242. "active file"
  243.      The news server has to keep track of what articles it carries, and
  244.      what groups exist.  All this information in stored in the active
  245.      file, which is rather large, as you might surmise.
  246.  
  247. "bogus groups"
  248.      A group that exists in the `.newsrc' file, but isn't known to the
  249.      server (i.e.,  it isn't in the active file), is a *bogus group*.
  250.      This means that the group probably doesn't exist (any more).
  251.  
  252. "server"
  253.      A machine one can connect to and get news (or mail) from.
  254.  
  255. "select method"
  256.      A structure that specifies the backend, the server and the virtual
  257.      server parameters.
  258.  
  259. "virtual server"
  260.      A named select method.  Since a select method defines all there is
  261.      to know about connecting to a (physical) server, taking the thing
  262.      as a whole is a virtual server.
  263.  
  264. "washing"
  265.      Taking a buffer and running it through a filter of some sort.  The
  266.      result will (more often than not) be cleaner and more pleasing
  267.      than the original.
  268.  
  269. "ephemeral groups"
  270.      Most groups store data on what articles you have read.  "Ephemeral"
  271.      groups are groups that will have no data stored--when you exit the
  272.      group, it'll disappear into the aether.
  273.  
  274. "solid groups"
  275.      This is the opposite of ephemeral groups.  All groups listed in the
  276.      group buffer are solid groups.
  277.  
  278. "sparse articles"
  279.      These are article placeholders shown in the summary buffer when
  280.      `gnus-build-sparse-threads' has been switched on.
  281.  
  282. 
  283. File: gnus.info,  Node: Customization,  Next: Troubleshooting,  Prev: Terminology,  Up: Appendices
  284.  
  285. Customization
  286. =============
  287.  
  288.    All variables are properly documented elsewhere in this manual.  This
  289. section is designed to give general pointers on how to customize Gnus
  290. for some quite common situations.
  291.  
  292. * Menu:
  293.  
  294. * Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere.
  295. * Slow Terminal Connection::  You run a remote Emacs.
  296. * Little Disk Space::         You feel that having large setup files is icky.
  297. * Slow Machine::              You feel like buying a faster machine.
  298.  
  299. 
  300. File: gnus.info,  Node: Slow/Expensive Connection,  Next: Slow Terminal Connection,  Up: Customization
  301.  
  302. Slow/Expensive NNTP Connection
  303. ------------------------------
  304.  
  305.    If you run Emacs on a machine locally, and get your news from a
  306. machine over some very thin strings, you want to cut down on the amount
  307. of data Gnus has to get from the NNTP server.
  308.  
  309. `gnus-read-active-file'
  310.      Set this to `nil', which will inhibit Gnus from requesting the
  311.      entire active file from the server.  This file is often v.  large.
  312.      You also have to set `gnus-check-new-newsgroups' and
  313.      `gnus-check-bogus-newsgroups' to `nil' to make sure that Gnus
  314.      doesn't suddenly decide to fetch the active file anyway.
  315.  
  316. `gnus-nov-is-evil'
  317.      This one has to be `nil'.  If not, grabbing article headers from
  318.      the NNTP server will not be very fast.  Not all NNTP servers
  319.      support XOVER; Gnus will detect this by itself.
  320.  
  321. 
  322. File: gnus.info,  Node: Slow Terminal Connection,  Next: Little Disk Space,  Prev: Slow/Expensive Connection,  Up: Customization
  323.  
  324. Slow Terminal Connection
  325. ------------------------
  326.  
  327.    Let's say you use your home computer for dialing up the system that
  328. runs Emacs and Gnus.  If your modem is slow, you want to reduce (as
  329. much as possible) the amount of data sent over the wires.
  330.  
  331. `gnus-auto-center-summary'
  332.      Set this to `nil' to inhibit Gnus from re-centering the summary
  333.      buffer all the time.  If it is `vertical', do only vertical
  334.      re-centering.  If it is neither `nil' nor `vertical', do both
  335.      horizontal and vertical recentering.
  336.  
  337. `gnus-visible-headers'
  338.      Cut down on the headers included in the articles to the minimum.
  339.      You can, in fact, make do without them altogether--most of the
  340.      useful data is in the summary buffer, anyway.  Set this variable to
  341.      `^NEVVVVER' or `From:', or whatever you feel you need.
  342.  
  343. `gnus-article-display-hook'
  344.      Set this hook to all the available hiding commands:
  345.           (setq gnus-article-display-hook
  346.                 '(gnus-article-hide-headers gnus-article-hide-signature
  347.                   gnus-article-hide-citation))
  348.  
  349. `gnus-use-full-window'
  350.      By setting this to `nil', you can make all the windows smaller.
  351.      While this doesn't really cut down much generally, it means that
  352.      you have to see smaller portions of articles before deciding that
  353.      you didn't want to read them anyway.
  354.  
  355. `gnus-thread-hide-subtree'
  356.      If this is non-`nil', all threads in the summary buffer will be
  357.      hidden initially.
  358.  
  359. `gnus-updated-mode-lines'
  360.      If this is `nil', Gnus will not put information in the buffer mode
  361.      lines, which might save some time.
  362.  
  363. 
  364. File: gnus.info,  Node: Little Disk Space,  Next: Slow Machine,  Prev: Slow Terminal Connection,  Up: Customization
  365.  
  366. Little Disk Space
  367. -----------------
  368.  
  369.    The startup files can get rather large, so you may want to cut their
  370. sizes a bit if you are running out of space.
  371.  
  372. `gnus-save-newsrc-file'
  373.      If this is `nil', Gnus will never save `.newsrc'--it will only
  374.      save `.newsrc.eld'.  This means that you will not be able to use
  375.      any other newsreaders than Gnus.  This variable is `t' by default.
  376.  
  377. `gnus-save-killed-list'
  378.      If this is `nil', Gnus will not save the list of dead groups.  You
  379.      should also set `gnus-check-new-newsgroups' to `ask-server' and
  380.      `gnus-check-bogus-newsgroups' to `nil' if you set this variable to
  381.      `nil'.  This variable is `t' by default.
  382.  
  383. 
  384. File: gnus.info,  Node: Slow Machine,  Prev: Little Disk Space,  Up: Customization
  385.  
  386. Slow Machine
  387. ------------
  388.  
  389.    If you have a slow machine, or are just really impatient, there are a
  390. few things you can do to make Gnus run faster.
  391.  
  392.    Set `gnus-check-new-newsgroups' and `gnus-check-bogus-newsgroups' to
  393. `nil' to make startup faster.
  394.  
  395.    Set `gnus-show-threads', `gnus-use-cross-reference' and
  396. `gnus-nov-is-evil' to `nil' to make entering and exiting the summary
  397. buffer faster.
  398.  
  399.    Set `gnus-article-display-hook' to `nil' to make article processing
  400. a bit faster.
  401.  
  402. 
  403. File: gnus.info,  Node: Troubleshooting,  Next: A Programmers Guide to Gnus,  Prev: Customization,  Up: Appendices
  404.  
  405. Troubleshooting
  406. ===============
  407.  
  408.    Gnus works *so* well straight out of the box--I can't imagine any
  409. problems, really.
  410.  
  411.    Ahem.
  412.  
  413.   1. Make sure your computer is switched on.
  414.  
  415.   2. Make sure that you really load the current Gnus version.  If you
  416.      have been running GNUS, you need to exit Emacs and start it up
  417.      again before Gnus will work.
  418.  
  419.   3. Try doing an `M-x gnus-version'.  If you get something that looks
  420.      like `Gnus v5.46; nntp 4.0' you have the right files loaded.  If,
  421.      on the other hand, you get something like `NNTP 3.x' or `nntp
  422.      flee', you have some old `.el' files lying around.  Delete these.
  423.  
  424.   4. Read the help group (`G h' in the group buffer) for a FAQ and a
  425.      how-to.
  426.  
  427.   5. Gnus works on many recursive structures, and in some extreme (and
  428.      very rare) cases Gnus may recurse down "too deeply" and Emacs will
  429.      beep at you.  If this happens to you, set `max-lisp-eval-depth' to
  430.      500 or something like that.
  431.  
  432.    If all else fails, report the problem as a bug.
  433.  
  434.    If you find a bug in Gnus, you can report it with the `M-x gnus-bug'
  435. command. `M-x set-variable RET debug-on-error RET t RET', and send me
  436. the backtrace.  I will fix bugs, but I can only fix them if you send me
  437. a precise description as to how to reproduce the bug.
  438.  
  439.    You really can never be too detailed in a bug report.  Always use the
  440. `M-x gnus-bug' command when you make bug reports, even if it creates a
  441. 10Kb mail each time you use it, and even if you have sent me your
  442. environment 500 times before.  I don't care.  I want the full info each
  443. time.
  444.  
  445.    It is also important to remember that I have no memory whatsoever.
  446. If you send a bug report, and I send you a reply, and then you just send
  447. back "No, it's not! Moron!", I will have no idea what you are insulting
  448. me about.  Always over-explain everything.  It's much easier for all of
  449. us--if I don't have all the information I need, I will just mail you
  450. and ask for more info, and everything takes more time.
  451.  
  452.    If the problem you're seeing is very visual, and you can't quite
  453. explain it, copy the Emacs window to a file (with `xwd', for instance),
  454. put it somewhere it can be reached, and include the URL of the picture
  455. in the bug report.
  456.  
  457.    If you just need help, you are better off asking on
  458. `gnu.emacs.gnus'.  I'm not very helpful.
  459.  
  460.    You can also ask on the ding mailing list--`ding@gnus.org'.  Write
  461. to `ding-request@gnus.org' to subscribe.
  462.  
  463. 
  464. File: gnus.info,  Node: A Programmers Guide to Gnus,  Next: Emacs for Heathens,  Prev: Troubleshooting,  Up: Appendices
  465.  
  466. A Programmer's Guide to Gnus
  467. ============================
  468.  
  469.    It is my hope that other people will figure out smart stuff that Gnus
  470. can do, and that other people will write those smart things as well.  To
  471. facilitate that I thought it would be a good idea to describe the inner
  472. workings of Gnus.  And some of the not-so-inner workings, while I'm at
  473. it.
  474.  
  475.    You can never expect the internals of a program not to change, but I
  476. will be defining (in some details) the interface between Gnus and its
  477. backends (this is written in stone), the format of the score files
  478. (ditto), data structures (some are less likely to change than others)
  479. and general methods of operation.
  480.  
  481. * Menu:
  482.  
  483. * Gnus Utility Functions::   Common functions and variable to use.
  484. * Backend Interface::        How Gnus communicates with the servers.
  485. * Score File Syntax::        A BNF definition of the score file standard.
  486. * Headers::                  How Gnus stores headers internally.
  487. * Ranges::                   A handy format for storing mucho numbers.
  488. * Group Info::               The group info format.
  489. * Emacs/XEmacs Code::        Gnus can be run under all modern Emacsen.
  490. * Various File Formats::     Formats of files that Gnus use.
  491.  
  492. 
  493. File: gnus.info,  Node: Gnus Utility Functions,  Next: Backend Interface,  Up: A Programmers Guide to Gnus
  494.  
  495. Gnus Utility Functions
  496. ----------------------
  497.  
  498.    When writing small functions to be run from hooks (and stuff), it's
  499. vital to have access to the Gnus internal functions and variables.
  500. Below is a list of the most common ones.
  501.  
  502. `gnus-newsgroup-name'
  503.      This variable holds the name of the current newsgroup.
  504.  
  505. `gnus-find-method-for-group'
  506.      A function that returns the select method for GROUP.
  507.  
  508. `gnus-group-real-name'
  509.      Takes a full (prefixed) Gnus group name, and returns the unprefixed
  510.      name.
  511.  
  512. `gnus-group-prefixed-name'
  513.      Takes an unprefixed group name and a select method, and returns
  514.      the full (prefixed) Gnus group name.
  515.  
  516. `gnus-get-info'
  517.      Returns the group info list for GROUP.
  518.  
  519. `gnus-add-current-to-buffer-list'
  520.      Adds the current buffer to the list of buffers to be killed on Gnus
  521.      exit.
  522.  
  523. `gnus-continuum-version'
  524.      Takes a Gnus version string as a parameter and returns a floating
  525.      point number.  Earlier versions will always get a lower number
  526.      than later versions.
  527.  
  528. `gnus-group-read-only-p'
  529.      Says whether GROUP is read-only or not.
  530.  
  531. `gnus-news-group-p'
  532.      Says whether GROUP came from a news backend.
  533.  
  534. `gnus-ephemeral-group-p'
  535.      Says whether GROUP is ephemeral or not.
  536.  
  537. `gnus-server-to-method'
  538.      Returns the select method corresponding to SERVER.
  539.  
  540. `gnus-server-equal'
  541.      Says whether two virtual servers are equal.
  542.  
  543. `gnus-group-native-p'
  544.      Says whether GROUP is native or not.
  545.  
  546. `gnus-group-secondary-p'
  547.      Says whether GROUP is secondary or not.
  548.  
  549. `gnus-group-foreign-p'
  550.      Says whether GROUP is foreign or not.
  551.  
  552. `group-group-find-parameter'
  553.      Returns the parameter list of GROUP.  If given a second parameter,
  554.      returns the value of that parameter for GROUP.
  555.  
  556. `gnus-group-set-parameter'
  557.      Takes three parameters; GROUP, PARAMETER and VALUE.
  558.  
  559. `gnus-narrow-to-body'
  560.      Narrows the current buffer to the body of the article.
  561.  
  562. `gnus-check-backend-function'
  563.      Takes two parameters, FUNCTION and GROUP.  If the backend GROUP
  564.      comes from supports FUNCTION, return non-`nil'.
  565.  
  566.           (gnus-check-backend-function "request-scan" "nnml:misc")
  567.           => t
  568.  
  569. `gnus-read-method'
  570.      Prompts the user for a select method.
  571.  
  572. 
  573. File: gnus.info,  Node: Backend Interface,  Next: Score File Syntax,  Prev: Gnus Utility Functions,  Up: A Programmers Guide to Gnus
  574.  
  575. Backend Interface
  576. -----------------
  577.  
  578.    Gnus doesn't know anything about NNTP, spools, mail or virtual
  579. groups.  It only knows how to talk to "virtual servers".  A virtual
  580. server is a "backend" and some "backend variables".  As examples of the
  581. first, we have `nntp', `nnspool' and `nnmbox'.  As examples of the
  582. latter we have `nntp-port-number' and `nnmbox-directory'.
  583.  
  584.    When Gnus asks for information from a backend--say `nntp'--on
  585. something, it will normally include a virtual server name in the
  586. function parameters.  (If not, the backend should use the "current"
  587. virtual server.)  For instance, `nntp-request-list' takes a virtual
  588. server as its only (optional) parameter.  If this virtual server hasn't
  589. been opened, the function should fail.
  590.  
  591.    Note that a virtual server name has no relation to some physical
  592. server name.  Take this example:
  593.  
  594.      (nntp "odd-one"
  595.            (nntp-address "ifi.uio.no")
  596.            (nntp-port-number 4324))
  597.  
  598.    Here the virtual server name is `odd-one' while the name of the
  599. physical server is `ifi.uio.no'.
  600.  
  601.    The backends should be able to switch between several virtual
  602. servers.  The standard backends implement this by keeping an alist of
  603. virtual server environments that they pull down/push up when needed.
  604.  
  605.    There are two groups of interface functions: "required functions",
  606. which must be present, and "optional functions", which Gnus will always
  607. check for presence before attempting to call 'em.
  608.  
  609.    All these functions are expected to return data in the buffer
  610. `nntp-server-buffer' (` *nntpd*'), which is somewhat unfortunately
  611. named, but we'll have to live with it.  When I talk about "resulting
  612. data", I always refer to the data in that buffer.  When I talk about
  613. "return value", I talk about the function value returned by the
  614. function call.  Functions that fail should return `nil' as the return
  615. value.
  616.  
  617.    Some backends could be said to be "server-forming" backends, and
  618. some might be said not to be.  The latter are backends that generally
  619. only operate on one group at a time, and have no concept of "server" -
  620. they have a group, and they deliver info on that group and nothing more.
  621.  
  622.    In the examples and definitions I will refer to the imaginary backend
  623. `nnchoke'.
  624.  
  625. * Menu:
  626.  
  627. * Required Backend Functions::        Functions that must be implemented.
  628. * Optional Backend Functions::        Functions that need not be implemented.
  629. * Error Messaging::                   How to get messages and report errors.
  630. * Writing New Backends::              Extending old backends.
  631. * Hooking New Backends Into Gnus::    What has to be done on the Gnus end.
  632. * Mail-like Backends::                Some tips on mail backends.
  633.  
  634. 
  635. File: gnus.info,  Node: Required Backend Functions,  Next: Optional Backend Functions,  Up: Backend Interface
  636.  
  637. Required Backend Functions
  638. ..........................
  639.  
  640. `(nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD)'
  641.      ARTICLES is either a range of article numbers or a list of
  642.      `Message-ID's.  Current backends do not fully support either--only
  643.      sequences (lists) of article numbers, and most backends do not
  644.      support retrieval of `Message-ID's.  But they should try for both.
  645.  
  646.      The result data should either be HEADs or NOV lines, and the result
  647.      value should either be `headers' or `nov' to reflect this.  This
  648.      might later be expanded to `various', which will be a mixture of
  649.      HEADs and NOV lines, but this is currently not supported by Gnus.
  650.  
  651.      If FETCH-OLD is non-`nil' it says to try fetching "extra headers",
  652.      in some meaning of the word.  This is generally done by fetching
  653.      (at most) FETCH-OLD extra headers less than the smallest article
  654.      number in `articles', and filling the gaps as well.  The presence
  655.      of this parameter can be ignored if the backend finds it
  656.      cumbersome to follow the request.  If this is non-`nil' and not a
  657.      number, do maximum fetches.
  658.  
  659.      Here's an example HEAD:
  660.  
  661.           221 1056 Article retrieved.
  662.           Path: ifi.uio.no!sturles
  663.           From: sturles@ifi.uio.no (Sturle Sunde)
  664.           Newsgroups: ifi.discussion
  665.           Subject: Re: Something very droll
  666.           Date: 27 Oct 1994 14:02:57 +0100
  667.           Organization: Dept. of Informatics, University of Oslo, Norway
  668.           Lines: 26
  669.           Message-ID: <38o8e1$a0o@holmenkollen.ifi.uio.no>
  670.           References: <38jdmq$4qu@visbur.ifi.uio.no>
  671.           NNTP-Posting-Host: holmenkollen.ifi.uio.no
  672.           .
  673.  
  674.      So a `headers' return value would imply that there's a number of
  675.      these in the data buffer.
  676.  
  677.      Here's a BNF definition of such a buffer:
  678.  
  679.           headers        = *head
  680.           head           = error / valid-head
  681.           error-message  = [ "4" / "5" ] 2number " " <error message> eol
  682.           valid-head     = valid-message *header "." eol
  683.           valid-message  = "221 " <number> " Article retrieved." eol
  684.           header         = <text> eol
  685.  
  686.      If the return value is `nov', the data buffer should contain
  687.      "network overview database" lines.  These are basically fields
  688.      separated by tabs.
  689.  
  690.           nov-buffer = *nov-line
  691.           nov-line   = 8*9 [ field <TAB> ] eol
  692.           field      = <text except TAB>
  693.  
  694.      For a closer look at what should be in those fields, *note
  695.      Headers::..
  696.  
  697. `(nnchoke-open-server SERVER &optional DEFINITIONS)'
  698.      SERVER is here the virtual server name.  DEFINITIONS is a list of
  699.      `(VARIABLE VALUE)' pairs that define this virtual server.
  700.  
  701.      If the server can't be opened, no error should be signaled.  The
  702.      backend may then choose to refuse further attempts at connecting
  703.      to this server.  In fact, it should do so.
  704.  
  705.      If the server is opened already, this function should return a
  706.      non-`nil' value.  There should be no data returned.
  707.  
  708. `(nnchoke-close-server &optional SERVER)'
  709.      Close connection to SERVER and free all resources connected to it.
  710.      Return `nil' if the server couldn't be closed for some reason.
  711.  
  712.      There should be no data returned.
  713.  
  714. `(nnchoke-request-close)'
  715.      Close connection to all servers and free all resources that the
  716.      backend have reserved.  All buffers that have been created by that
  717.      backend should be killed.  (Not the `nntp-server-buffer', though.)
  718.      This function is generally only called when Gnus is shutting down.
  719.  
  720.      There should be no data returned.
  721.  
  722. `(nnchoke-server-opened &optional SERVER)'
  723.      If SERVER is the current virtual server, and the connection to the
  724.      physical server is alive, then this function should return a
  725.      non-`nil' vlue.  This function should under no circumstances
  726.      attempt to reconnect to a server we have lost connection to.
  727.  
  728.      There should be no data returned.
  729.  
  730. `(nnchoke-status-message &optional SERVER)'
  731.      This function should return the last error message from SERVER.
  732.  
  733.      There should be no data returned.
  734.  
  735. `(nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER)'
  736.      The result data from this function should be the article specified
  737.      by ARTICLE.  This might either be a `Message-ID' or a number.  It
  738.      is optional whether to implement retrieval by `Message-ID', but it
  739.      would be nice if that were possible.
  740.  
  741.      If TO-BUFFER is non-`nil', the result data should be returned in
  742.      this buffer instead of the normal data buffer.  This is to make it
  743.      possible to avoid copying large amounts of data from one buffer to
  744.      another, while Gnus mainly requests articles to be inserted
  745.      directly into its article buffer.
  746.  
  747.      If it is at all possible, this function should return a cons cell
  748.      where the `car' is the group name the article was fetched from,
  749.      and the `cdr' is the article number.  This will enable Gnus to
  750.      find out what the real group and article numbers are when fetching
  751.      articles by `Message-ID'.  If this isn't possible, `t' should be
  752.      returned on successful article retrieval.
  753.  
  754. `(nnchoke-request-group GROUP &optional SERVER FAST)'
  755.      Get data on GROUP.  This function also has the side effect of
  756.      making GROUP the current group.
  757.  
  758.      If FAST, don't bother to return useful data, just make GROUP the
  759.      current group.
  760.  
  761.      Here's an example of some result data and a definition of the same:
  762.  
  763.           211 56 1000 1059 ifi.discussion
  764.  
  765.      The first number is the status, which should be 211.  Next is the
  766.      total number of articles in the group, the lowest article number,
  767.      the highest article number, and finally the group name.  Note that
  768.      the total number of articles may be less than one might think
  769.      while just considering the highest and lowest article numbers, but
  770.      some articles may have been canceled.  Gnus just discards the
  771.      total-number, so whether one should take the bother to generate it
  772.      properly (if that is a problem) is left as an exercise to the
  773.      reader.
  774.  
  775.           group-status = [ error / info ] eol
  776.           error        = [ "4" / "5" ] 2<number> " " <Error message>
  777.           info         = "211 " 3* [ <number> " " ] <string>
  778.  
  779. `(nnchoke-close-group GROUP &optional SERVER)'
  780.      Close GROUP and free any resources connected to it.  This will be
  781.      a no-op on most backends.
  782.  
  783.      There should be no data returned.
  784.  
  785. `(nnchoke-request-list &optional SERVER)'
  786.      Return a list of all groups available on SERVER.  And that means
  787.      *all*.
  788.  
  789.      Here's an example from a server that only carries two groups:
  790.  
  791.           ifi.test 0000002200 0000002000 y
  792.           ifi.discussion 3324 3300 n
  793.  
  794.      On each line we have a group name, then the highest article number
  795.      in that group, the lowest article number, and finally a flag.
  796.  
  797.           active-file = *active-line
  798.           active-line = name " " <number> " " <number> " " flags eol
  799.           name        = <string>
  800.           flags       = "n" / "y" / "m" / "x" / "j" / "=" name
  801.  
  802.      The flag says whether the group is read-only (`n'), is moderated
  803.      (`m'), is dead (`x'), is aliased to some other group
  804.      (`=other-group') or none of the above (`y').
  805.  
  806. `(nnchoke-request-post &optional SERVER)'
  807.      This function should post the current buffer.  It might return
  808.      whether the posting was successful or not, but that's not
  809.      required.  If, for instance, the posting is done asynchronously,
  810.      it has generally not been completed by the time this function
  811.      concludes.  In that case, this function should set up some kind of
  812.      sentinel to beep the user loud and clear if the posting could not
  813.      be completed.
  814.  
  815.      There should be no result data from this function.
  816.  
  817. 
  818. File: gnus.info,  Node: Optional Backend Functions,  Next: Error Messaging,  Prev: Required Backend Functions,  Up: Backend Interface
  819.  
  820. Optional Backend Functions
  821. ..........................
  822.  
  823. `(nnchoke-retrieve-groups GROUPS &optional SERVER)'
  824.      GROUPS is a list of groups, and this function should request data
  825.      on all those groups.  How it does it is of no concern to Gnus, but
  826.      it should attempt to do this in a speedy fashion.
  827.  
  828.      The return value of this function can be either `active' or
  829.      `group', which says what the format of the result data is.  The
  830.      former is in the same format as the data from
  831.      `nnchoke-request-list', while the latter is a buffer full of lines
  832.      in the same format as `nnchoke-request-group' gives.
  833.  
  834.           group-buffer = *active-line / *group-status
  835.  
  836. `(nnchoke-request-update-info GROUP INFO &optional SERVER)'
  837.      A Gnus group info (*note Group Info::.) is handed to the backend
  838.      for alterations.  This comes in handy if the backend really
  839.      carries all the information (as is the case with virtual and imap
  840.      groups).  This function should destructively alter the info to
  841.      suit its needs, and should return the (altered) group info.
  842.  
  843.      There should be no result data from this function.
  844.  
  845. `(nnchoke-request-type GROUP &optional ARTICLE)'
  846.      When the user issues commands for "sending news" (`F' in the
  847.      summary buffer, for instance), Gnus has to know whether the
  848.      article the user is following up on is news or mail.  This
  849.      function should return `news' if ARTICLE in GROUP is news, `mail'
  850.      if it is mail and `unknown' if the type can't be decided.  (The
  851.      ARTICLE parameter is necessary in `nnvirtual' groups which might
  852.      very well combine mail groups and news groups.)  Both GROUP and
  853.      ARTICLE may be `nil'.
  854.  
  855.      There should be no result data from this function.
  856.  
  857. `(nnchoke-request-update-mark GROUP ARTICLE MARK)'
  858.      If the user tries to set a mark that the backend doesn't like, this
  859.      function may change the mark.  Gnus will use whatever this function
  860.      returns as the mark for ARTICLE instead of the original MARK.  If
  861.      the backend doesn't care, it must return the original MARK, and
  862.      not `nil' or any other type of garbage.
  863.  
  864.      The only use for this I can see is what `nnvirtual' does with
  865.      it--if a component group is auto-expirable, marking an article as
  866.      read in the virtual group should result in the article being
  867.      marked as expirable.
  868.  
  869.      There should be no result data from this function.
  870.  
  871. `(nnchoke-request-scan &optional GROUP SERVER)'
  872.      This function may be called at any time (by Gnus or anything else)
  873.      to request that the backend check for incoming articles, in one
  874.      way or another.  A mail backend will typically read the spool file
  875.      or query the POP server when this function is invoked.  The GROUP
  876.      doesn't have to be heeded--if the backend decides that it is too
  877.      much work just scanning for a single group, it may do a total scan
  878.      of all groups.  It would be nice, however, to keep things local if
  879.      that's practical.
  880.  
  881.      There should be no result data from this function.
  882.  
  883. `(nnchoke-request-group-description GROUP &optional SERVER)'
  884.      The result data from this function should be a description of
  885.      GROUP.
  886.  
  887.           description-line = name <TAB> description eol
  888.           name             = <string>
  889.           description      = <text>
  890.  
  891. `(nnchoke-request-list-newsgroups &optional SERVER)'
  892.      The result data from this function should be the description of all
  893.      groups available on the server.
  894.  
  895.           description-buffer = *description-line
  896.  
  897. `(nnchoke-request-newgroups DATE &optional SERVER)'
  898.      The result data from this function should be all groups that were
  899.      created after `date', which is in normal human-readable date
  900.      format.  The data should be in the active buffer format.
  901.  
  902. `(nnchoke-request-create-group GROUP &optional SERVER)'
  903.      This function should create an empty group with name GROUP.
  904.  
  905.      There should be no return data.
  906.  
  907. `(nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE)'
  908.      This function should run the expiry process on all articles in the
  909.      ARTICLES range (which is currently a simple list of article
  910.      numbers.)  It is left up to the backend to decide how old articles
  911.      should be before they are removed by this function.  If FORCE is
  912.      non-`nil', all ARTICLES should be deleted, no matter how new they
  913.      are.
  914.  
  915.      This function should return a list of articles that it did not/was
  916.      not able to delete.
  917.  
  918.      There should be no result data returned.
  919.  
  920. `(nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM'
  921.      &optional LAST)
  922.  
  923.      This function should move ARTICLE (which is a number) from GROUP
  924.      by calling ACCEPT-FORM.
  925.  
  926.      This function should ready the article in question for moving by
  927.      removing any header lines it has added to the article, and
  928.      generally should "tidy up" the article.  Then it should `eval'
  929.      ACCEPT-FORM in the buffer where the "tidy" article is.  This will
  930.      do the actual copying.  If this `eval' returns a non-`nil' value,
  931.      the article should be removed.
  932.  
  933.      If LAST is `nil', that means that there is a high likelihood that
  934.      there will be more requests issued shortly, so that allows some
  935.      optimizations.
  936.  
  937.      The function should return a cons where the `car' is the group
  938.      name and the `cdr' is the article number that the article was
  939.      entered as.
  940.  
  941.      There should be no data returned.
  942.  
  943. `(nnchoke-request-accept-article GROUP &optional SERVER LAST)'
  944.      This function takes the current buffer and inserts it into GROUP.
  945.      If LAST in `nil', that means that there will be more calls to this
  946.      function in short order.
  947.  
  948.      The function should return a cons where the `car' is the group
  949.      name and the `cdr' is the article number that the article was
  950.      entered as.
  951.  
  952.      There should be no data returned.
  953.  
  954. `(nnchoke-request-replace-article ARTICLE GROUP BUFFER)'
  955.      This function should remove ARTICLE (which is a number) from GROUP
  956.      and insert BUFFER there instead.
  957.  
  958.      There should be no data returned.
  959.  
  960. `(nnchoke-request-delete-group GROUP FORCE &optional SERVER)'
  961.      This function should delete GROUP.  If FORCE, it should really
  962.      delete all the articles in the group, and then delete the group
  963.      itself.  (If there is such a thing as "the group itself".)
  964.  
  965.      There should be no data returned.
  966.  
  967. `(nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER)'
  968.      This function should rename GROUP into NEW-NAME.  All articles in
  969.      GROUP should move to NEW-NAME.
  970.  
  971.      There should be no data returned.
  972.  
  973. 
  974. File: gnus.info,  Node: Error Messaging,  Next: Writing New Backends,  Prev: Optional Backend Functions,  Up: Backend Interface
  975.  
  976. Error Messaging
  977. ...............
  978.  
  979.    The backends should use the function `nnheader-report' to report
  980. error conditions--they should not raise errors when they aren't able to
  981. perform a request.  The first argument to this function is the backend
  982. symbol, and the rest are interpreted as arguments to `format' if there
  983. are multiple of them, or just a string if there is one of them.  This
  984. function must always returns `nil'.
  985.  
  986.      (nnheader-report 'nnchoke "You did something totally bogus")
  987.      
  988.      (nnheader-report 'nnchoke "Could not request group %s" group)
  989.  
  990.    Gnus, in turn, will call `nnheader-get-report' when it gets a `nil'
  991. back from a server, and this function returns the most recently
  992. reported message for the backend in question.  This function takes one
  993. argument--the server symbol.
  994.  
  995.    Internally, these functions access BACKEND`-status-string', so the
  996. `nnchoke' backend will have its error message stored in
  997. `nnchoke-status-string'.
  998.  
  999. 
  1000. File: gnus.info,  Node: Writing New Backends,  Next: Hooking New Backends Into Gnus,  Prev: Error Messaging,  Up: Backend Interface
  1001.  
  1002. Writing New Backends
  1003. ....................
  1004.  
  1005.    Many backends are quite similar.  `nnml' is just like `nnspool', but
  1006. it allows you to edit the articles on the server.  `nnmh' is just like
  1007. `nnml', but it doesn't use an active file, and it doesn't maintain
  1008. overview databases.  `nndir' is just like `nnml', but it has no concept
  1009. of "groups", and it doesn't allow editing articles.
  1010.  
  1011.    It would make sense if it were possible to "inherit" functions from
  1012. backends when writing new backends.  And, indeed, you can do that if you
  1013. want to.  (You don't have to if you don't want to, of course.)
  1014.  
  1015.    All the backends declare their public variables and functions by
  1016. using a package called `nnoo'.
  1017.  
  1018.    To inherit functions from other backends (and allow other backends to
  1019. inherit functions from the current backend), you should use the
  1020. following macros:
  1021.  
  1022. `nnoo-declare'
  1023.      This macro declares the first parameter to be a child of the
  1024.      subsequent parameters.  For instance:
  1025.  
  1026.           (nnoo-declare nndir
  1027.             nnml nnmh)
  1028.  
  1029.      `nndir' has declared here that it intends to inherit functions from
  1030.      both `nnml' and `nnmh'.
  1031.  
  1032. `defvoo'
  1033.      This macro is equivalent to `defvar', but registers the variable as
  1034.      a public server variable.  Most state-oriented variables should be
  1035.      declared with `defvoo' instead of `defvar'.
  1036.  
  1037.      In addition to the normal `defvar' parameters, it takes a list of
  1038.      variables in the parent backends to map the variable to when
  1039.      executing a function in those backends.
  1040.  
  1041.           (defvoo nndir-directory nil
  1042.             "Where nndir will look for groups."
  1043.             nnml-current-directory nnmh-current-directory)
  1044.  
  1045.      This means that `nnml-current-directory' will be set to
  1046.      `nndir-directory' when an `nnml' function is called on behalf of
  1047.      `nndir'.  (The same with `nnmh'.)
  1048.  
  1049. `nnoo-define-basics'
  1050.      This macro defines some common functions that almost all backends
  1051.      should have.
  1052.  
  1053.           (nnoo-define-basics nndir)
  1054.  
  1055. `deffoo'
  1056.      This macro is just like `defun' and takes the same parameters.  In
  1057.      addition to doing the normal `defun' things, it registers the
  1058.      function as being public so that other backends can inherit it.
  1059.  
  1060. `nnoo-map-functions'
  1061.      This macro allows mapping of functions from the current backend to
  1062.      functions from the parent backends.
  1063.  
  1064.           (nnoo-map-functions nndir
  1065.             (nnml-retrieve-headers 0 nndir-current-group 0 0)
  1066.             (nnmh-request-article 0 nndir-current-group 0 0))
  1067.  
  1068.      This means that when `nndir-retrieve-headers' is called, the first,
  1069.      third, and fourth parameters will be passed on to
  1070.      `nnml-retrieve-headers', while the second parameter is set to the
  1071.      value of `nndir-current-group'.
  1072.  
  1073. `nnoo-import'
  1074.      This macro allows importing functions from backends.  It should be
  1075.      the last thing in the source file, since it will only define
  1076.      functions that haven't already been defined.
  1077.  
  1078.           (nnoo-import nndir
  1079.             (nnmh
  1080.              nnmh-request-list
  1081.              nnmh-request-newgroups)
  1082.             (nnml))
  1083.  
  1084.      This means that calls to `nndir-request-list' should just be passed
  1085.      on to `nnmh-request-list', while all public functions from `nnml'
  1086.      that haven't been defined in `nndir' yet should be defined now.
  1087.  
  1088.    Below is a slightly shortened version of the `nndir' backend.
  1089.  
  1090.      ;;; nndir.el --- single directory newsgroup access for Gnus
  1091.      ;; Copyright (C) 1995,96 Free Software Foundation, Inc.
  1092.      
  1093.      ;;; Code:
  1094.      
  1095.      (require 'nnheader)
  1096.      (require 'nnmh)
  1097.      (require 'nnml)
  1098.      (require 'nnoo)
  1099.      (eval-when-compile (require 'cl))
  1100.      
  1101.      (nnoo-declare nndir
  1102.        nnml nnmh)
  1103.      
  1104.      (defvoo nndir-directory nil
  1105.        "Where nndir will look for groups."
  1106.        nnml-current-directory nnmh-current-directory)
  1107.      
  1108.      (defvoo nndir-nov-is-evil nil
  1109.        "*Non-nil means that nndir will never retrieve NOV headers."
  1110.        nnml-nov-is-evil)
  1111.      
  1112.      (defvoo nndir-current-group "" nil nnml-current-group nnmh-current-group)
  1113.      (defvoo nndir-top-directory nil nil nnml-directory nnmh-directory)
  1114.      (defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail)
  1115.      
  1116.      (defvoo nndir-status-string "" nil nnmh-status-string)
  1117.      (defconst nndir-version "nndir 1.0")
  1118.      
  1119.      ;;; Interface functions.
  1120.      
  1121.      (nnoo-define-basics nndir)
  1122.      
  1123.      (deffoo nndir-open-server (server &optional defs)
  1124.        (setq nndir-directory
  1125.              (or (cadr (assq 'nndir-directory defs))
  1126.                  server))
  1127.        (unless (assq 'nndir-directory defs)
  1128.          (push `(nndir-directory ,server) defs))
  1129.        (push `(nndir-current-group
  1130.                ,(file-name-nondirectory (directory-file-name nndir-directory)))
  1131.              defs)
  1132.        (push `(nndir-top-directory
  1133.                ,(file-name-directory (directory-file-name nndir-directory)))
  1134.              defs)
  1135.        (nnoo-change-server 'nndir server defs))
  1136.      
  1137.      (nnoo-map-functions nndir
  1138.        (nnml-retrieve-headers 0 nndir-current-group 0 0)
  1139.        (nnmh-request-article 0 nndir-current-group 0 0)
  1140.        (nnmh-request-group nndir-current-group 0 0)
  1141.        (nnmh-close-group nndir-current-group 0))
  1142.      
  1143.      (nnoo-import nndir
  1144.        (nnmh
  1145.         nnmh-status-message
  1146.         nnmh-request-list
  1147.         nnmh-request-newgroups))
  1148.      
  1149.      (provide 'nndir)
  1150.  
  1151. 
  1152. File: gnus.info,  Node: Hooking New Backends Into Gnus,  Next: Mail-like Backends,  Prev: Writing New Backends,  Up: Backend Interface
  1153.  
  1154. Hooking New Backends Into Gnus
  1155. ..............................
  1156.  
  1157.    Having Gnus start using your new backend is rather easy--you just
  1158. declare it with the `gnus-declare-backend' functions.  This will enter
  1159. the backend into the `gnus-valid-select-methods' variable.
  1160.  
  1161.    `gnus-declare-backend' takes two parameters--the backend name and an
  1162. arbitrary number of "abilities".
  1163.  
  1164.    Here's an example:
  1165.  
  1166.      (gnus-declare-backend "nnchoke" 'mail 'respool 'address)
  1167.  
  1168.    The abilities can be:
  1169.  
  1170. `mail'
  1171.      This is a mailish backend--followups should (probably) go via mail.
  1172.  
  1173. `post'
  1174.      This is a newsish backend--followups should (probably) go via news.
  1175.  
  1176. `post-mail'
  1177.      This backend supports both mail and news.
  1178.  
  1179. `none'
  1180.      This is neither a post nor mail backend--it's something completely
  1181.      different.
  1182.  
  1183. `respool'
  1184.      It supports respooling--or rather, it is able to modify its source
  1185.      articles and groups.
  1186.  
  1187. `address'
  1188.      The name of the server should be in the virtual server name.  This
  1189.      is true for almost all backends.
  1190.  
  1191. `prompt-address'
  1192.      The user should be prompted for an address when doing commands like
  1193.      `B' in the group buffer.  This is true for backends like `nntp',
  1194.      but not `nnmbox', for instance.
  1195.  
  1196. 
  1197. File: gnus.info,  Node: Mail-like Backends,  Prev: Hooking New Backends Into Gnus,  Up: Backend Interface
  1198.  
  1199. Mail-like Backends
  1200. ..................
  1201.  
  1202.    One of the things that separate the mail backends from the rest of
  1203. the backends is the heavy dependence by the mail backends on common
  1204. functions in `nnmail.el'.  For instance, here's the definition of
  1205. `nnml-request-scan':
  1206.  
  1207.      (deffoo nnml-request-scan (&optional group server)
  1208.        (setq nnml-article-file-alist nil)
  1209.        (nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group))
  1210.  
  1211.    It simply calls `nnmail-get-new-mail' with a few parameters, and
  1212. `nnmail' takes care of all the moving and splitting of the mail.
  1213.  
  1214.    This function takes four parameters.
  1215.  
  1216. METHOD
  1217.      This should be a symbol to designate which backend is responsible
  1218.      for the call.
  1219.  
  1220. EXIT-FUNCTION
  1221.      This function should be called after the splitting has been
  1222.      performed.
  1223.  
  1224. TEMP-DIRECTORY
  1225.      Where the temporary files should be stored.
  1226.  
  1227. GROUP
  1228.      This optional argument should be a group name if the splitting is
  1229.      to be performed for one group only.
  1230.  
  1231.    `nnmail-get-new-mail' will call BACKEND`-save-mail' to save each
  1232. article.  BACKEND`-active-number' will be called to find the article
  1233. number assigned to this article.
  1234.  
  1235.    The function also uses the following variables:
  1236. BACKEND`-get-new-mail' (to see whether to get new mail for this
  1237. backend); and BACKEND`-group-alist' and BACKEND`-active-file' to
  1238. generate the new active file.  BACKEND`-group-alist' should be a
  1239. group-active alist, like this:
  1240.  
  1241.      (("a-group" (1 . 10))
  1242.       ("some-group" (34 . 39)))
  1243.  
  1244.